The Self-Describing Files (SDF) interface in GrADS version 1.6 beta

.
GrADS is a data visualization and analysis package from COLA, the Center for Ocean-Land- Atmosphere studies. The primary definition of what is needed in a netCDF or HDF-SDS file to be compatible with SDF interface in GrADS version 1.6 beta is the netCDF conventions adopted by participants in the Cooperative Ocean Atmosphere Research Data Service.

In addition, the UNIDATA Program Center's udunits package version 1.10 or later is needed.


The COARDS conventions imply that the time:units attribute value should contain an origin, and GrADS' SDF interface requires it. Put in terms of function calls in the Udunits package, the time:units attribute value must encounter success with the calls utScan, utIsTime, and utHasOrigin (these are the C names; in FORTRAN, the function call names are utdec, uttime, and utorigin).

Additionally, a time:units attribute specifying "months" is not supported, because that unit has no fixed length. However, data that has a monthly time step is easily described using a "days since origin_date" form of units attribute value. The time step is checked and if it's greater than 28 days (whether the units attribute specifies days or hours), monthly is assumed.


Multiple horizontal grids (AKA staggered grids) are supported by the COARDS conventions, but not by GrADS' SDF interface at this time.


Climatology files are difficult to use at this time. Work is under way to correct this in future releases.


What GrADS describes as an X coordinate variable is recognized by values of the units attribute (in a one-dimensional variable of the same name as the dimension, the netCDF definition of a coordinate variable) of: 
	"degrees_east", "degree_east", "degrees_E", or "degree_E"

Y coordinate variables are recognized if they have units attribute values of: 

	"degrees_north", "degree_north", "degrees_N", or "degree_N"


Z coordinate variables are recognized if they have a unit of length that can be converted by the udunits package to "feet", or a unit of pressure that can be converted to "pascals", or a unit of isothermics that can be converted to "kelvins", or have one of the following explicit values (case is not significant): 

	"mb", "sigma_level", "level", "layer", "layers",
	"degreesk", or "degrees_k"



Any non-coordinate variable with dimensions consisting of the X, Y, T, and optionally Z dimensions discovered as described above are considered displayable by the SDF interface, and may be used in expressions. As of this release, the COARDS specification of dimension order is required. That order is (including the optional Z dimension): T, Z, Y, X. Note, this is the ordering for C programs and for the ncgen and ncdump commands. In FORTRAN, this order would, of course, be reversed. Any variable lacking any of the X, Y, or T dimensions (and Z, if present in the file) will not be marked as usable by the SDF interface, and if the order is not correct, strange results may occur. If a Z dimension is present in an SDF file, it is assumed to pertain to all data variables in that SDF file. Thus single-layer and multi-layer variables cannot be successfully mixed in a single SDF file. These restrictions are planned to be relaxed in subsequent releases.


The syntax for the sdfopen command consists of one required argument (the path to the SDF file), and two optional arguments: 

    sdfopen SDFpath [template #time_steps]
The optional arguments are for using a time series of files as a single entity. For example, if one had daily uwnd data in uwnd.1989.nc and uwnd.1990.nc, one could enter: 
    sdfopen /Data/uwnd.1989.nc uwnd.%y4.nc 730
Thereafter in the session, times from either data file can be accessed.


For additional info on GrADS' SDF interface, contact hoop@cdc.noaa.gov.